home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1997 November / Macworld (1997-11).dmg / Shareware World / Newton / HyperNewt 2.0 Release / HyperNewt API / HyperNewt API.txt
Text File  |  1997-09-01  |  10KB  |  313 lines
  1. ============================================================
  2. HyperNewt 2.0 Developer API
  3.  
  4. Last Update: September 1, 1997
  5.  
  6. Copyright (c) 1997. Foundation Systems. All Rights Reserved.
  7. ============================================================
  8.  
  9.  
  10. =================
  11. TABLE OF CONTENTS
  12. =================
  13.  
  14.   1. Developer API
  15.   
  16.     A. The HyperLink Manager
  17.     B. Creating a HyperLink Manager
  18.     C. SaveHyperLink Function Overview
  19.     D. ShowHyperLink Function Overview
  20.     E. Sample HyperLink Manager Soup Entry
  21.     F. Soup Definitions and Soup Names
  22.     G. Sample Code And Submitting HLM's 
  23.  
  24.  
  25.  
  26. -------==============================================================-------
  27. ---===                       1. DEVELOPER API                         ===---
  28. -------==============================================================-------
  29.  
  30.  
  31. The following information is for developers who are interested in creating
  32. HyperLink Managers for their own applications. Any application that supports
  33. 2.x routing of data can use HyperLinks. A developer need only to create a
  34. HyperLink Manager (HLM) that handles the saving of and display of HyperLinked
  35. data.
  36.  
  37.  
  38.  
  39.     ======================================
  40.     ---=== A. THE HYPERLINK MANAGER ===---
  41.     ======================================
  42.     
  43. There are two types of HyperLink Managers, differentiated only by the type of
  44. data that they support:
  45.  
  46. 1. Soup data: Data being HyperLinked are soup entries
  47.  
  48. 2. Non-soup data: Data being HyperLinked do not belong to a soup.
  49.  
  50.  
  51. Among the default HLM's installed with HyperNewt, the following applications
  52. use (1) HLM's to store HyperLinks:
  53.  
  54.         Calls
  55.         Cigar Box
  56.         Dates
  57.         Gulliver
  58.         Home Inventory
  59.         In/Out Box
  60.         MORGAN
  61.         Names
  62.         NewtWorks
  63.         Notes
  64.  
  65. Among the default HLM's installed with HyperNewt, the following applications
  66. use (2) HLM's to store HyperLinks:
  67.  
  68.         Dates
  69.         Extras Drawer
  70.         Copperfield (Newton Books)
  71.  
  72.  
  73. As you can see, some applications have both a Soup HLM and a Non-Soup HLM to
  74. handle all the types of data that they deal with.
  75.  
  76.  
  77.  
  78.     =============================================
  79.     ---=== B. CREATING A HYPERLINK MANAGER ===---
  80.     =============================================
  81.  
  82. HLM's are store in the HyperLink Manager soup on a Newton device. Each HLM must
  83. contain 3 required slots:
  84.  
  85. ======================
  86. Soup HLM required slot
  87. ======================
  88.  
  89.   a. soupname: The name of the soup where the data being HyperLinked is
  90.      stored.
  91.  
  92. ==========================
  93. Non-Soup HLM required slot
  94. ==========================
  95.  
  96.   a. appsymbol: The symbol for the application from which the HyperLinked
  97.      data belongs.
  98.   
  99. ========================================================
  100. HLM required slots -- ALL HLM'S MUST CONTAIN THESE SLOTS
  101. ========================================================
  102.  
  103.   a. SaveHyperLink: Function that creates the HyperLink information frame for
  104.      HyperNewt.
  105.  
  106.   b. ShowHyperLink: Function that takes a HyperLink information frame and
  107.      displays the found entry, if there is one, to the user.
  108.  
  109.  
  110.  
  111. The SaveHyperLink and the ShowHyperLink methods are outlined in more detail
  112. below:
  113.  
  114.  
  115.  
  116.     ================================================
  117.     ---=== C. SaveHyperLink FUNCTION OVERVIEW ===---
  118.     ================================================
  119.  
  120. This function takes the soup entry or data that is being HyperLinked and
  121. returns a frame containing a HyperLink Information Frame and a displayable text
  122. title and icon to HyperNewt. The HyperLink Information Frame must contain the
  123. following slots for each type of HyperLink Manager being created:
  124.  
  125.  
  126.         // For Soup HLM's
  127.  
  128.     DefConst('kDefaultSoupHyperLinkInfoFrame,
  129.         {
  130.             soupname: nil,
  131.             timestamp: nil,
  132.             
  133.             shortTitle: nil, // Optional string
  134.         }
  135.     );
  136.  
  137.  
  138.         // For Non-Soup HLM's 
  139.  
  140.     DefConst('kDefaultNonSoupHyperLinkInfoFrame,
  141.         {
  142.             appsymbol: nil,
  143.             timestamp: nil,
  144.             
  145.             shortTitle: nil, // Optional string
  146.         }
  147.     );
  148.  
  149.  
  150. The SaveHyperLink functions takes one parameter, the soup entry or data being
  151. hyperlinked. It is the responsibility for the developer to decide, beyond the
  152. required slots, what information she wants to add to the HyperLink Information
  153. Frame that can locate a HyperLinked entry at a later date.
  154.  
  155. Many people will choose to store an EntryAlias, for soup entries, in the
  156. HyperLink Information Frame. Remember that if an entry is moved to another
  157. card, then that entry will be unresolvable from a HyperLink.
  158.  
  159.  
  160.  
  161.     ================================================
  162.     ---=== D. ShowHyperLink FUNCTION OVERVIEW ===---
  163.     ================================================
  164.  
  165. This function takes a HyperLink Information Frame to some data that has been
  166. HyperLinked and displays the entry, if it exists, to the user. Since the
  167. developer has written the SaveHyperLink method, she would know how to retrieve
  168. the data and display it to the user.
  169.  
  170. If your application saves data to soups, you may want to try using HyperNewt's
  171. default method for displaying a HyperLinked entry. Call the root method with
  172. the following syntax:
  173.  
  174.     constant kAppSymbol := '|HyperNewt:ATOW|;
  175.  
  176.     GetRoot().(kAppSymbol).DefaultShowHyperLink with (entry, appSymbol);
  177.  
  178. where appsymbol is your application symbol and entry is your soup entry.
  179. HyperNewt will automatically open your application and call the method
  180. ShowFoundItem with (entry, {}) as its parameters:
  181.  
  182.     GetRoot().(appSymbol):ShowFoundItem(entry, {});
  183.  
  184. If you cannot find the entry that has been HyperLinked, return nil and
  185. HyperNewt will alert the user that the original item could not be found.
  186.  
  187.  
  188.  
  189.     ====================================================
  190.     ---=== E. SAMPLE HYPERLINK MANAGER SOUP ENTRY ===---
  191.     ====================================================
  192.  
  193. The following code snippet details a sample HLM for the Notes application. Any
  194. note that is HyperLinked will use the following HLM:
  195.  
  196.  
  197.     /* kPaperRollSaveHyperLinkFunc
  198.      * ---------------------------
  199.      * This function extracts the title string and icon from the stationery's
  200.      * dataDef. It saves in the HyperLink Information frame the shortTitle
  201.      * (taken simply from the entry's title slot), an EntryAlias for the
  202.      * entry being HyperLinked, its class symbol, the soup name (required),
  203.      * and the entry's timestamp (required).
  204.      *
  205.      * This function returns a standard information frame back to HyperNewt
  206.      * to continue creating the HyperLink.
  207.      *
  208.      */
  209.  
  210. DefConst('kPaperRollSaveHyperLinkFunc, func(entry) begin
  211.     local entryDataDef := GetEntryDataDef(entry);
  212.     local hyperlinkinfo := Clone(kDefaultSoupHyperLinkInfoFrame);
  213.     local title, icon;
  214.         
  215.     if entryDataDef then begin
  216.         title := entryDataDef:StringExtract(entry, 1);
  217.         icon := entryDataDef.icon;
  218.     end;
  219.  
  220.     hyperlinkinfo.shortTitle := entry.title;
  221.     hyperlinkinfo._alias := MakeEntryAlias(entry);
  222.     hyperlinkinfo.class := ClassOf(entry);
  223.     hyperlinkinfo.soupName := ROM_paperRollSoupName;
  224.     hyperlinkinfo.timestamp := entry.timestamp;
  225.         
  226.     return { title: title, icon: icon, hyperlinkinfo: hyperlinkinfo };
  227. end);
  228.  
  229.  
  230.     /* kPaperRollShowHyperLinkFunc
  231.      * ---------------------------
  232.      * This function tries to first resolve the entry alias
  233.      * for the note stored in the hyperlink. If present, the function
  234.      * calls a default method of HyperNewt to display the entry,
  235.      * otherwise nil is returned (and HyperNewt will alert the
  236.      * user that the original item could not be found).
  237.      *
  238.      */
  239.  
  240. DefConst('kPaperRollShowHyperLinkFunc, func(hyperlinkInfo) begin
  241.     local entry := EntryFromObj(hyperlinkinfo);
  242.     local app := GetRoot().('|HyperNewt:ATOW|);
  243.     
  244.     if entry and app then begin
  245.         if app:PrefsLookup('displayWithNotepad) then
  246.             return call app.DefaultShowHyperLink with (entry, 'paperroll);
  247.         else return call app.DefaultShowHyperLink with (entry, kAppSymbol);
  248.     end;
  249.  
  250.     return nil;
  251. end);
  252.  
  253.  
  254. The complete HyperLink Manager soup entry frame for the Notepad HLM is shown
  255. below. Add this entry to the HLM soup to support the use of HyperLinks in the
  256. Notepad application:
  257.  
  258.   {
  259.     soupname: ROM_paperRollSoupName,
  260.     SaveHyperLink: kPaperRollSaveHyperLinkFunc,
  261.     ShowHyperLink: kPaperRollShowHyperLinkFunc,
  262.   }
  263.  
  264.  
  265.  
  266.     ====================================================
  267.     ---=== F. SOUP DEFINITIONS AND SOUPNAMES ===---
  268.     ====================================================
  269.  
  270. The following are the soup definition and soup name for the HyperLink Manager
  271. Soup. When creating a HyperLink Manager, be sure to check for the presence of
  272. the HyperLink Manager soup before hand. To ensure proper operation, *DO NOT*
  273. create the HyperLink Manager Soup if it is not present. 
  274.  
  275. HyperNewt installs the default HLM Soup only if it is not currently installed.
  276. If you create and add one entry to the HLM soup, new users will not be able to
  277. use HyperLinks in any application other than your own.
  278.  
  279.  
  280. DefConst('kHyperLinkManagerSoupName, "HyperLink Manager");
  281. DefConst('kHyperLinkManagerSoupDef,
  282.     {    
  283.         name: kHyperLinkManagerSoupName,
  284.         userName: kHyperLinkManagerSoupName,
  285.         ownerApp: kAppSymbol,
  286.         ownerAppName: kAppName,
  287.         userDescr: "This soup is used by" && kAppName,
  288.                                     
  289.         indexes: [
  290.                     { structure: 'slot, path: 'appsymbol, type: 'symbol }, 
  291.                     { structure: 'slot, path: 'soupname, type: 'string },
  292.                  ],
  293.     }
  294. );
  295.  
  296.  
  297.  
  298.     =================================================
  299.     ---=== G. SAMPLE CODE AND SUBMITTING HLM'S ===---
  300.     =================================================
  301.  
  302. The code for all the default HLMs that ship with HyperNewt is available from
  303. the HyperNewt web page at:
  304.  
  305.     http://www.tow.com/newton/hypernewt/
  306.     
  307. If you come up with a better HLM for any of the default HLM's, email your
  308. solution to Foundation Systems and we will consider it for inclusion in the
  309. next release of HyperNewt. If you have an application that supports HyperLinks
  310. and would like your application's HLM to be included among the default HLM's
  311. that ship with HyperNewt, again, email us and your HLM will be considered for
  312. inclusion.
  313.